home *** CD-ROM | disk | FTP | other *** search
/ QRZ! Ham Radio 8 / QRZ Ham Radio Callsign Database - Volume 8.iso / mac / german / tcpip / gp160.exe / #GPRI.EXE / GPRI.DOC < prev    next >
Text File  |  1993-05-14  |  14KB  |  398 lines
  1.  
  2.  
  3.  
  4.                GPRI - Das Graphic Packet Remote-Interface
  5.  
  6.                                Version 1.0
  7.  
  8.                     (C) Ulf Saran, DH1DAE, 1990-1993
  9.  
  10.  
  11.                    Dieses Dokument wurde erstellt von
  12.       Stefan Pfeiffer, DD9EP@DB0IZ, 930401, letzte Modifikation 930405
  13.  
  14.  
  15.  
  16.                        S P E Z I F I K A T I O N
  17.                        -------------------------
  18.  
  19.  
  20.  
  21. 0. Inhaltsverzeichnis
  22.  
  23.  
  24.   1. Einführung
  25.  
  26.   2. Interrupt-Funktionen des Interrupt 2Fh
  27.     2.1. Funktion FFh - Get Version Number
  28.     2.2. Funktion 00h - Register as Remoteprogram
  29.     2.3. Funktion 01h - Get FileTransfer-Address
  30.     2.4. Funktion 02h - Get QSO-Data-Address
  31.  
  32.   3. GPRI-Routinen
  33.     3.1. Die GPRI-Sende-Routine
  34.     3.2. Die GPRI-FileTransfer-Routine
  35.     3.3. Die GPRI-QSO-Daten-Routine
  36.  
  37.   4. Erforderliche Routinen des Remote-Programms
  38.     4.1. Die Initialisierungs-Routine
  39.     4.2. Die Empfangs-Routine
  40.     4.3. Die Strategie-Routine
  41.     4.4. Die Exit-Routine
  42.  
  43.   5. Schematischer Ablauf eines GPRI-Programms
  44.  
  45.   6. Tips und Tricks
  46.  
  47.  
  48. 1. Einführung
  49.  
  50.   Das GPRI ist eine Sammlung von Funktionen, die es externen DOS-Programmen
  51.   erlauben, mit GP zu kommunizieren und GP in begrenztem Umfang zu steuern.
  52.   So kann das Remoteprogramm direkt aus seinem Programmlauf heraus Texte senden
  53.   und empfangen. Dabei muß es sich nicht um die Bedienung eines TNC kümmern,
  54.   da diese Aufgaben völlig von GP übernommen werden.
  55.  
  56.   Beim Aufruf eines interaktiven Remoteprogramms (das also das GPRI nutzt),
  57.   lädt das GPRI das Programm in den Speicher und führt, nachdem sich das
  58.   Programm als GPRI-Programm "angemeldet" hat, eine Initialisierungsroutine
  59.   aus, in der das Programm z.B. eine Startmeldung ausgeben kann.
  60.   Dann wird eine bestimmte Routine im Remoteprogramm immer dann angesprungen,
  61.   wenn ein Text auf dem betreffenden Kanal empfangen wurde. Das Remote-
  62.   programm kann dann auf den empfangenen Text reagieren und eine Antwort
  63.   zurücksenden.
  64.   Auf Anforderung des Programms wird es dann vom GPRI wieder aus dem Speicher
  65.   entfernt.
  66.   Das GPRI basiert also völlig auf einer Client/Server-Struktur zwischen GP
  67.   und dem Remoteprogramm, da das GPRI-Programm Dienste wie "String senden",
  68.   "Datei senden" und "QSO-Daten erfragen" direkt von GP anfordert.
  69.  
  70.   Dadurch wird es möglich, Remoteprogramme über PR genauso zu bedienen, als
  71.   würden sie unter DOS laufen, nämlich durch eine interaktive Kommunikation
  72.   mit dem Programm. Dadurch bieten sich viel weitere Möglichkeiten für Remote-
  73.   programme als bisher.
  74.  
  75.   Dieses Dokument beschreibt die Schnittstelle zwischen GP und dem interaktiven
  76.   Remoteprogramm. Sie ist von der verwendeten Programmiersprache unabhängig,
  77.   sie sollte aber Interrupts aufrufen können und Assembler-Einbindung unter-
  78.   stützen. Ich setze ein gewisses Maß an Programmierkenntnissen vorraus, da
  79.   das GPRI und dessen Programmierung relativ komplex und fehleranfällig sind.
  80.  
  81.   Dies ist dadurch bedingt, daß es bei einem GPRI-Programm kein eigentliches
  82.   Hauptprogramm gibt, sondern fast alles in den Routinen erledigt wird, die
  83.   von GPRI aufgerufen werden.
  84.  
  85.  
  86. 2. Interrupt-Funktionen des Interrupt 2Fh
  87.  
  88.   Zur ersten Kontaktaufnahme mit dem GPRI bedient sich das Remoteprogramm des
  89.   Interrupt 2Fh. Über ihn kann es feststellen, ob es überhaupt unter GPRI
  90.   läuft und welche Version des GPRI unterstützt wird. Weiterhin kann
  91.   es die Einsprungadressen für die eigentliche Sende-Routine erfragen
  92.   und seine eigenen Routinen beim GPRI "registrieren" lassen.
  93.  
  94.   Um das GPRI anzusprechen, muß das Remoteprogramm in AH den Wert DFh laden,
  95.   in AL wird die Funktionsnummer eingetragen.
  96.  
  97.  
  98.   2.1. Funktion FFh - Get Version Number
  99.  
  100.     Mit dieser Funktion kann das Remoteprogramm feststellen, ob es überhaupt
  101.     von GP aus gestartet wurde, und welche GPRI-Version unterstützt wird.
  102.  
  103.     Eingabe:
  104.       AH: DFh      (Code, um das GPRI anzusprechen)
  105.       AL: FFh      (Funktionsnummer)
  106.  
  107.     Ausgabe:
  108.       Wenn AX gleich 4750h ist, läuft das Remoteprogramm unter GPRI (4750h
  109.       entspricht in ASCII 'GP').
  110.       Dann gilt:
  111.         BH: Versionsnummer
  112.         BL: Revisionsnummer
  113.  
  114.       Bei GPRI Version 1.0 enthält BH also den Wert 1, BL den Wert 0.
  115.  
  116.       Wenn AX ungleich 4750h ist, dann läuft das Remoteprogramm unter DOS,
  117.       und das GPRI ist nicht installiert.
  118.  
  119.   
  120.   2.2. Funktion 00h - Register as Remoteprogram
  121.  
  122.     Mit dieser Funktion meldet sich das Remote-Programm beim GPRI an, und
  123.     erhält im Gegenzug die Adresse der GPRI-Sende-Routine und ein Handle, was
  124.     das Programm gegenüber dem GPRI identifiziert.
  125.     Diese Funktion muß von einem Remote-Programm aufgerufen werden, bevor es
  126.     irgendeine andere GPRI-Routine aufruft.
  127.  
  128.     Eingabe:
  129.       AH: DFh      (Code, um das GPRI anzusprechen)
  130.       AL: 00h      (Funktionsnummer)
  131.       ES: Segment der folgenden Datenstruktur
  132.       BX: Offset der folgenden Datenstruktur
  133.  
  134.         Prefixsegment des Remoteprogramms   : WORD
  135.         Adresse der Initialisierungsroutine : POINTER
  136.         Adresse der Empfangs-Routine        : POINTER
  137.         Adresse der Strategie-Routine       : POINTER
  138.         Adresse der Exit-Routine            : POINTER
  139.  
  140.     Ausgabe:
  141.       Wenn AX ungleich 4750h ('GP'), dann: Fehler!
  142.       Wenn AX gleich 4750h, dann gilt:
  143.         ES: Segment der GPRI-Sende-Routine
  144.         BX: Offset der GPRI-Sende-Routine
  145.         CL: Handle des Remote-Programms
  146.  
  147.     Erläuterung der Sende-Routine siehe:  3.1.
  148.     Erläuterung der Routinen in der Datenstruktur siehe:  4.
  149.  
  150.  
  151.   2.3. Funktion 01h - Get FileTransfer-Address
  152.  
  153.     Mit dieser Funktion kann das Remoteprogramm die Adresse der GPRI-Routine
  154.     erfragen, um eine Datei auszusenden.
  155.  
  156.     Eingabe:
  157.       AH: DFh      (Code, um das GPRI anzusprechen)
  158.       AL: 01h      (Funktionsnummer)
  159.  
  160.     Ausgabe:
  161.       Wenn AX ungleich 4750h ('GP'), dann: Fehler!
  162.       Wenn AX gleich 4750h, dann gilt:
  163.         ES: Segment der GPRI-Datei-Sende-Routine
  164.         BX: Offset der GPRI-Datei-Sende-Routine
  165.  
  166.     Erläuterung der Datei-Sende-Routine siehe:  3.2.
  167.  
  168.  
  169.   2.4. Funktion 02h - Get QSO-Data-Address
  170.  
  171.     Durch diese Funktion erhält das Remoteprogramm die Adresse einer GPRI-
  172.     Routine, die wiederum die aktuellen QSO-Daten zurückgibt.
  173.  
  174.     Eingabe:
  175.       AH: DFh      (Code, um das GPRI anzusprechen)
  176.       AL: 02h      (Funktionsnummer)
  177.  
  178.     Ausgabe:
  179.       Wenn AX ungleich 4750h ('GP'): Fehler!
  180.       Wenn AX gleich 4750h, dann gilt:
  181.         ES: Segment der GPRI-QSO-Daten-Routine
  182.         BX: Offset der GPRI-QSO-Daten-Routine
  183.  
  184.     Erläuterung der QSO-Daten-Routine siehe:  3.3.
  185.  
  186.  
  187. 3. GPRI-Routinen
  188.  
  189.  
  190.   3.1. Die GPRI-Sende-Routine
  191.  
  192.     Die Adresse dieser Routine wird von der Interrupt-Funktion 00h zurück-
  193.     gegeben. Sie muß wie alle GPRI-Routinen mit einem FAR CALL aufgerufen
  194.     werden.
  195.  
  196.     Dabei haben die Register folgende Bedeutung:
  197.  
  198.     BL: Handle des Remote-Programms
  199.     BH: Prompt-Flag (1 -> Sende-Buffer leeren, 0 -> Sende-Buffer nicht
  200.         leeren)
  201.     CL: Macro-Flag (1 -> Macro-Auswertung vornehmen, 0 -> Auswertung nicht
  202.         vornehmen)
  203.     ES: Segment des zu sendenden Strings
  204.     DX: Offset des zu sendenden Strings
  205.  
  206.     Es handelt sich bei dem String um einen Pascal-String mit führendem
  207.     Längenbyte. Er wird nicht durch eine binäre 0 terminiert.
  208.     Nach Aufruf der Funktion hat das AX-Register den Wert 1, wenn kein Fehler
  209.     auftrat. Konnte der String nicht gesendet werden (Keine freien TNC-Puffer),
  210.     enthält das AX-Register den Wert 0.
  211.  
  212.  
  213.   3.2. Die GPRI-FileTransfer-Routine
  214.  
  215.     Diese Routine erlaubt es dem Remoteprogramm, eine beliebige Datei auszu-
  216.     senden. Vorher muss die Adresse der Routine über die Interruptfunktion
  217.     01h erfragt werden. Auch diese Routine wird über einen FAR CALL auf-
  218.     gerufen.
  219.  
  220.     Bedeutung der Register:
  221.  
  222.     BL: Handle des Remoteprogramms
  223.     BH: Modus des FileTransfers
  224.         0: Textdatei
  225.         1: Binärdatei 1:1 (Kein AutoBin)
  226.         2: AutoBin
  227.  
  228.     ES: Segment des Dateinamens
  229.     DX: Offset des Dateinamens
  230.  
  231.     Dabei ist zu beachten, daß es sich bei dem Dateinamen um einen String
  232.     nach Pascal-Art handelt, also ein String mit führendem Längenbyte. Er
  233.     wird nicht mit einer binären 0 terminiert.
  234.  
  235.     Nach Aufruf der Funktion enthält AX eine 1, wenn kein Fehler auftrat,
  236.     sonst eine 0.
  237.  
  238.     Während eines Dateitransfers wird die Strategie-Routine NICHT aufgerufen!
  239.  
  240.  
  241.   3.3. Die GPRI-QSO-Daten-Routine
  242.  
  243.     Über diese Routine kann das Remoteprogramm Informationen über das
  244.     aktuelle QSO abrufen. Die Adresse muss vorher über die Funktion 02h
  245.     erfragt werden, der Aufruf erfolgt über einen FAR CALL.
  246.  
  247.     Bedeutung der Register:
  248.  
  249.     BL: Handle des Remote-Programms
  250.     ES: Segment der folgenden Datenstruktur
  251.     DX: Offset der folgenden Datenstruktur
  252.  
  253.       MyCall : String[9]     (MyCall auf dem aktuellen Kanal)
  254.       Call   : String[9]     (Call der Gegenstation)
  255.       Name   : String[80]    (Name der Gegenstation)
  256.       Pfad   : String[255]   (Connect-Pfad der Gegenstation)
  257.  
  258.     Dabei ist wieder zu beachten, daß es sich um Pascal-Strings handeln
  259.     muß. Der MyCall-String ist also 10 Bytes lang: 1 Längenbyte und 9
  260.     Datenbytes. Die Gesamtlänge der Struktur beträgt also 357 Bytes.
  261.     Wurde die Funktion erfolgreich ausgeführt, enthält das AX-Register eine 1,
  262.     ansonsten eine 0.
  263.  
  264.  
  265. 4. Erforderliche Routinen des Remote-Programms
  266.  
  267.   Die Adressen der folgenden Routinen müssen dem GPRI über die Funktion 00h
  268.   zugänglich gemacht werden. Alle diese Routinen müssen FAR kompiliert
  269.   sein!
  270.  
  271.  
  272.   4.1. Die Initialisierungs-Routine
  273.  
  274.     Eingabe:
  275.       Keine
  276.  
  277.     Ausgabe:
  278.       BL: Programmbeendigung (0 -> Nein, 1 -> Ja)
  279.  
  280.     Diese Routine wird vom GPRI aufgerufen, nachdem das Remote-Programm in
  281.     den Speicher geladen wurde. Hier kann es z.b. eine Begrüssung ausgeben.
  282.  
  283.     ACHTUNG: Aus dem Hauptprogramm heraus sollten keine GPRI-Funktionen
  284.     wie "Text senden" aufgerufen werden, da dies zu Problemen führen kann.
  285.     Deshalb sollte eine Begrüssung wirklich nur in der Initialisierungs-
  286.     routine ausgegeben werden.
  287.  
  288.  
  289.   4.2. Die Empfangs-Routine
  290.  
  291.     Eingabe:
  292.       ES: Segment des empfangenen Strings
  293.       DX: Offset des empfangenen Strings
  294.  
  295.       Dabei handelt es sich wiederum um einen String im Pascal-Format.
  296.  
  297.     Ausgabe:
  298.       BL: Programmbeendigung (0 -> Nein, 1 -> Ja)
  299.  
  300.  
  301.     Diese Routine wird immer aufgerufen, wenn ein Text empfangen wurde.
  302.     Die Routine kann den empfangenen Text auswerten, einen Antwort-Text
  303.     oder eine Datei zurücksenden und eventuell BL auf 1 setzen, um sich
  304.     selbst zu beenden.
  305.  
  306.  
  307.   4.3. Die Strategie-Routine
  308.  
  309.     Eingabe:
  310.       Keine
  311.  
  312.     Ausgabe:
  313.       BL: Programmbeendigung (0 -> Nein, 1 -> Ja)
  314.  
  315.     Diese Routine wird von GP periodisch aufgerufen, außer bei FileTransfers.
  316.     Sie lässt sich somit als Timer-Routine einsetzen, oder um das Ende eines
  317.     FileTransfers erkennen zu können.
  318.  
  319.  
  320.   4.4. Die Exit-Routine
  321.  
  322.     Eingabe:
  323.       Keine
  324.  
  325.     Ausgabe:
  326.       Keine
  327.  
  328.     Diese Routine wird aufgerufen, bevor das GPRI das Remote-Programm aus dem
  329.     Speicher entfernt. Dies kann in folgenden Fällen geschehen:
  330.     a) Das Remoteprogramm hat BL auf 1 gesetzt und fordert damit seine
  331.        Beendigung an.
  332.     b) Das QSO wird vorzeitig durch Re- oder Disconnect unterbrochen.
  333.     c) GP wird beendet.
  334.  
  335.  
  336. 5. Schematischer Ablauf eines GPRI-Programms
  337.  
  338.   Um das GPRI-Prinzip etwas klarer werden zu lassen, wird im folgenden
  339.   der prinzipelle Ablauf eines GPRI-Programms beschrieben.
  340.   Es empfiehlt sich, die Programme sowohl unter GPRI als auch unter DOS
  341.   lauffähig zu machen. Das Programm sollte also Eingaben von der Tastatur
  342.   entgegennehmen und seine Texte auf dem Monitor ausgeben, wenn es fest-
  343.   stellt, daß es nicht unter dem GPRI läuft. Alternativ dazu kann sich das
  344.   Programm natürlich auch selbst beenden.
  345.  
  346.   Nun das Schema eines GPRI-Programms:
  347.  
  348.   PROZEDUR Init       (FAR!)
  349.   {
  350.     Startmeldung über Sende-Routine ausgeben
  351.     BL auf 0 setzen (Kein Programmende)
  352.   }
  353.  
  354.   PROZEDUR Empfang    (FAR!)
  355.   {
  356.     Empfangstext analysieren
  357.     Antworttext oder Datei zurücksenden
  358.     Eventuell BL auf 1 setzen, um Programm zu beenden
  359.   }
  360.  
  361.   PROZEDUR Ende       (FAR!)
  362.   {
  363.     Eventuell Speicher freigeben und ähnliches
  364.   }
  365.  
  366.   PROZEDUR Main       (Hauptprogramm)
  367.   {
  368.     Version des GPRI feststellen
  369.  
  370.     Wenn Fehler, dann unter DOS normal arbeiten oder beenden
  371.  
  372.     Adressen der Routinen Init,Empfang und Ende sowie das Prefix-Segment an
  373.     das GPRI melden, Adresse der Sende-Routine und Handle merken
  374.  
  375.     Eventuell Adressen der QSO-Daten-Routine und der FileTransfer-Routine
  376.     erfragen und merken
  377.  
  378.     Programm beenden und im Speicher lassen (evtl. durch Befehl der
  379.     Programmiersprache oder durch INT 21h, Funktion 31h)
  380.   }
  381.  
  382.  
  383. 6. Tips und Tricks
  384.  
  385.   Es ist wichtig, den Heap- und Stackbedarf des Remote-Programms zu begrenzen,
  386.   da es ja speicherresident bleibt. Auch der Stack muß nicht zu groß bemessen
  387.   sein, da später der Stack von GP mitbenutzt wird. Er sollte ihn auf den
  388.   kleinstmöglichen Wert einstellen.
  389.  
  390.  
  391.  
  392.   Viel Spaß mit den unglaublichen Möglichkeiten interaktiver Remote-
  393.   Programme und der Programmierung des GPRI.
  394.  
  395.  
  396.                                               Vy 73, Stefan Pfeiffer, DD9EP
  397.  
  398.